Skip to main content

Countries States Cities Service

NPM

Table of contents​

  1. Mission
  2. Getting started
  3. Usage
  4. Contributors
  5. Need help
  6. Licence
  7. Sponsor

Mission​

  • I've never found any complete library to get all world countries, states, and cities. I want to develop the best one. Of course, contributors are welcome!!
  • I took this data as a starting point.

Getting started​

To get started with this library, you need to install it and add it to your project.

Installation​

Countries States Cities Service is available as an npm package.

# npm
npm install countries-states-cities-service

# yarn
yarn add countries-states-cities-service

Import​

Import single named import as follow:

import { Countries, States, Cities } from 'countries-states-cities-service'

Usage​

The code snippet below shows how to put into action countries-states-cities-service in some common use cases.

Countries​

  • Get all countries.
const countries = Countries.getCountries()
  • Get all countries by asc sort.
const countries = Countries.getCountries({
  sort: {
    mode: 'asc',
  },
})
  • Get all countries by desc sort.
const countries = Countries.getCountries({
  sort: {
    mode: 'desc',
  },
})
  • Get all countries by alphabetical sort.
const countries = Countries.getCountries({
  sort: {
    mode: 'alphabetical',
    key: 'iso2',
  },
})
  • Get all countries with localization.
const countries = Countries.getCountries({ locale: 'it' })
  • Get a country by iso2 code.
const countries = Countries.getCountries({ filters: { iso2: 'US' } })
  • Get a country by iso2 code and localization.
const countries = Countries.getCountries({
  filters: { iso2: 'IT' },
  locale: 'it',
})
  • Get a country by iso3 code.
const countries = Countries.getCountries({ filters: { iso3: 'ITA' } })

States​

  • Get all states.
const states = States.getStates()
  • Get all states by asc sort.
const states = States.getStates({
  sort: {
    mode: 'asc',
  },
})
  • Get all states by desc sort.
const states = States.getStates({
  sort: {
    mode: 'desc',
  },
})
  • Get all states by alphabetical sort.
const states = States.getStates({
  sort: {
    mode: 'alphabetical',
    key: 'name',
  },
})
  • Get all states with localization.
const states = States.getStates({ locale: 'it' })
  • Get states by country code.
const states = States.getStates({ filters: { country_code: 'IT' } })
  • Get states by country code and localization (available only for Italian states for now).
const states = States.getStates({
  filters: { country_code: 'IT' },
  locale: 'it',
})
  • Get regions by country code (available only for Italian states for now).
const states = States.getStates({
  filters: {
    country_code: 'IT',
    is_region: true,
  },
})
  • Get a state by country code and state code.
const states = States.getStates({
  filters: {
    country_code: 'IT',
    state_code: 'GE',
  },
})

Cities​

  • Get all cities.
const cities = Cities.getCities()
  • Get all cities by asc sort.
const cities = Cities.getCities({
  sort: {
    mode: 'asc',
  },
})
  • Get all cities by desc sort.
const cities = Cities.getCities({
  sort: {
    mode: 'desc',
  },
})
  • Get all cities by alphabetical sort.
const cities = Cities.getCities({
  sort: {
    mode: 'alphabetical',
    key: 'name',
  },
})
  • Get Italian cities.
const cities = Cities.getCities({
  filters: {
    country_code: 'IT',
  },
})
  • Get Italian Ligurian cities.
const cities = Cities.getCities({
  filters: {
    country_code: 'IT',
    state_code: '42', // Region iso2
  },
})

Contributors​

Any contribution is appreciated. You can get started with the steps below:

  1. Fork this repository (learn how to do this here).

  2. Clone the forked repository.

  3. Make your changes and create a pull request (learn how to do this).

  4. I will attend to your pull request and provide some feedback.

Need help?​

Ping me on Twitter

License​

This repository is licensed under the MIT License.

Don't be shy! 😜

❤️ Sponsor